Other issue¶

What should I do if the device becomes excessively hot?¶

Confirm whether the temperature is actually too high¶

Run the following command to obtain the current device temperature:

qpi-config dump temperature

If the temperature exceeds 80 °C, take cooling measures immediately.

Identify the heat source¶

Check CPU utilization and frequency:

# Check CPU utilization.
top -b -n 1 | head -20

# Check the operating frequency of each CPU core to determine whether it remains at the maximum frequency.
cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq

# Check whether the performance governor is enabled.
cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

Check GPU utilization:

cat /sys/class/kgsl/kgsl-3d0/gpu_busy_percentage 2>/dev/null
cat /sys/class/kgsl/kgsl-3d0/max_gpuclk 2>/dev/null

Check storage utilization:

iostat -x 1 3   # Display %util.

Software cooling measures¶

Reduce the maximum CPU frequency:

# Display available frequencies.
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies

# Set the maximum frequency, for example, to 1.6 GHz.
echo 1651200 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq

Switch the CPU governor to schedutil:

echo schedutil > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

Reduce the maximum GPU frequency:

# Display available frequencies.
cat /sys/class/kgsl/kgsl-3d0/devfreq/available_frequencies

# Set the maximum frequency, for example, to 550 MHz.
echo 550000000 > /sys/class/kgsl/kgsl-3d0/devfreq/max_freq

Check for processes with abnormal CPU usage:

ps aux --sort=-%cpu | head -10

Physical cooling measures¶

Place the development board in a well-ventilated environment.
Install an active cooling module. The fan should increase its speed automatically when the device temperature exceeds the configured threshold.

What should I do if a library does not work correctly?¶

Identify and classify the issue¶

Link error: The compiler reports cannot find -lxxx, or the error cannot open shared object file occurs at runtime.
Runtime crash: The application reports undefined symbol: xxx or triggers a Segmentation fault.
Functional error: The library loads successfully, but a specific API does not respond or returns an unexpected error code.

Check whether the library file exists and verify the library search path¶

# 1. Locate the library.
find /usr/lib /usr/local/lib /lib -name "libxxx.so*"

# 2. Check whether the dynamic linker recognizes the library.
ldconfig -p | grep libxxx

# 3. Check whether LD_LIBRARY_PATH contains the directory.
echo $LD_LIBRARY_PATH

If the library is in a nonstandard directory, set LD_LIBRARY_PATH, or add the directory to a configuration file under /etc/ld.so.conf.d/ and run ldconfig to update the cache.

Check dependencies to resolve undefined symbols¶

# List the library dependencies (safer than ldd because it does not execute code).
readelf -d /path/to/libxxx.so | grep NEEDED

# Check whether a symbol is defined in the library.
nm -D /path/to/libxxx.so | grep "  T " | grep symbol_name

# Alternatively:
readelf -s /path/to/libxxx.so | grep symbol_name

An undefined symbol usually indicates a library version mismatch or a missing dependency. If the symbol exists but the application still reports an error, the cause may be link order or ABI incompatibility.

Check library version and ABI compatibility¶

# Display the embedded library version string.
strings /path/to/libxxx.so | grep -i version

# Display the library SONAME.
readelf -d /path/to/libxxx.so | grep SONAME

If the application was linked against libxxx.so.1 but only libxxx.so.2 is installed, an ABI change may cause a runtime crash even if the required symbol exists. A symbolic link, such as ln -s libxxx.so.2 libxxx.so.1, can be used as a temporary workaround. For a long-term solution, rebuild the application or install a compatible library version.

Trace dynamic loading at runtime¶

# 1. Display the libraries loaded by the dynamic linker.
LD_DEBUG=libs ./your_app 2>&1 | grep libxxx

# 2. Trace attempts to open library files.
strace -e openat,open ./your_app 2>&1 | grep libxxx

# 3. If the application crashes immediately, inspect it with gdb.
gdb ./your_app
(gdb) run
(gdb) bt   # Display the call stack after the crash.

How can I update a third-party driver?¶

Obtain the official SDK. See Image Build for download instructions.
Add the third-party driver source code under sources/quectel-src/kernel.
Add the device tree node for the peripheral to sources/quectel-src/kernel/qcom-6.6/arch/arm64/boot/dts/qcom/qcs6490-idp-pi.dts.
Build and flash the image, and then verify the driver.

What should I do if system performance is poor?¶

Poor performance is usually caused by a combination of CPU scheduling, memory pressure, storage I/O, thermal throttling, and software configuration.

Identify the bottleneck¶

# 1. Display the 1-, 5-, and 15-minute load averages.
uptime
# A sustained load average greater than the number of CPU cores indicates CPU pressure.

# 2. Display per-core CPU utilization by category (user, system, soft interrupt, and idle).
mpstat -P ALL 1 3

# 3. Display memory and swap usage.
free -h
# Less than 10% available memory with nonzero swap usage indicates memory pressure.

# 4. Check storage I/O. A %util value near 100% indicates a storage bottleneck.
iostat -x 1 3

# 5. Check temperature and CPU frequency for thermal throttling.
qpi-config dump temperature
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq

Interpret the key metrics as follows:

High %us: CPU-intensive user-space workload.
High %sy: Excessive system call or driver overhead.
High %wa: Storage I/O bottleneck.
High %si: Excessive software interrupts.
Temperature above 80 °C: Potential thermal throttling.
Very little available memory in free -h: Memory pressure.

Apply targeted optimization¶

CPU bottleneck (%us or %sy consistently above 60%)¶

Identify the processes with the highest CPU utilization.
Reduce the load generated by cameras and other peripherals.
Increase the real-time priority of critical threads, for example, by adjusting the scheduling policy.

Memory bottleneck (very low available memory and nonzero swap usage)¶

Identify the ten processes with the highest memory usage.
Remove unnecessary log files.
Check for DMA-BUF or ION memory leaks.

Storage I/O bottleneck (%util in iostat close to 100%)¶

Identify the processes generating the most write I/O.
Reduce unnecessary log writes.
Check for processes that write files too frequently.

Thermal throttling (frequency reduction caused by high temperature)¶

Confirm whether the system has triggered frequency throttling.
Apply active physical or software cooling measures.

How can I configure a service to start at boot?¶

systemd is the standard init system used by most mainstream Linux distributions, including Yocto-based systems. It provides dependency management, automatic restart, and environment variable configuration.

Create a service unit file¶

Create a .service file under /etc/systemd/system/, for example, my-camera.service:

[Unit]
Description=My Camera Service
After=network.target   # Start after the network is available.

[Service]
Type=simple            # Other types include forking and oneshot.
ExecStart=/usr/bin/my_script.sh
Restart=on-failure     # Restart automatically after a failure.
User=root              # Run as root.
WorkingDirectory=/opt/my_app

[Install]
WantedBy=multi-user.target   # Start when the system enters multi-user mode.

Enable and start the service¶

# Reload the systemd configuration.
sudo systemctl daemon-reload

# Enable the service at boot.
sudo systemctl enable my-camera.service

# Start the service immediately, if required.
sudo systemctl start my-camera.service

# Display the service status.
sudo systemctl status my-camera.service

How can I install a third-party driver?¶

Obtain the driver module: Obtain the third-party driver source code and cross-compile it in an environment that matches the development board’s kernel version to generate a .ko module.
Transfer the driver module: Transfer the compiled .ko file to the development board through scp, adb, or a USB flash drive.
Load and unload the driver:

Load the driver with insmod:

insmod your_driver.ko

Unload the driver with rmmod:

rmmod your_driver

Run lsmod to list all loaded modules:

lsmod

What should I do if no solution is available?¶

Visit the Quectel FAQ page.
Ask a question on the Quectel Developer Forum.